//+------------------------------------------------------------------+
//|                                               ColorGenerator.mqh |
//|                             Copyright 2000-2025, MetaQuotes Ltd. |
//|                                             https://www.mql5.com |
//+------------------------------------------------------------------+

//+------------------------------------------------------------------+
//| CColorGenerator 类：默认颜色生成器工具类                          |
//| 核心定位：提供“预定义调色板+动态生成”结合的颜色生成能力，为需要批量分配唯一颜色的场景（如多序列图表、分类数据标注）提供统一颜色管理 |
//| 核心特性：                                                      |
//|  1. 预定义调色板：内置 20 种高辨识度的默认颜色（涵盖红、蓝、绿、紫等常见色系，避免相近色导致的视觉混淆）； |
//|  2. 动态扩展能力：当预定义颜色用尽后，自动通过“异或运算”生成新颜色，确保颜色数量无上限； |
//|  3. 状态可重置：支持重置颜色生成状态（恢复预定义调色板、重置生成索引），适配重复使用场景； |
//|  4. 轻量易用：无需复杂配置，实例化后调用 `Next()` 即可获取下一个颜色，降低使用成本； |
//| 适用场景：所有需要“批量、唯一、高辨识度颜色”的场景，典型如：        |
//|  - 多序列图表（如K线图中同时显示多个指标线、均线，为每条线分配唯一颜色）； |
//|  - 分类数据可视化（如柱状图中不同类别数据、散点图中不同分组样本，用颜色区分类别）； |
//|  - 动态UI元素生成（如自定义控件中批量创建标签、按钮，用颜色区分不同状态/类型）； |
//|  - 日志/调试标注（如多模块日志输出时，用不同颜色标记各模块日志，提升可读性）； |
//+------------------------------------------------------------------+
class CColorGenerator
  {
private:
   int               m_index;                // 颜色生成索引（当前已分配到的颜色在调色板中的位置，从0开始）
   bool              m_generate;             // 动态生成开关（false=使用预定义调色板；true=预定义颜色用尽，开始动态生成新颜色）
   uint              m_current_palette[20];  // 当前调色板（初始为预定义颜色数组的副本，动态生成时会更新其中元素）
   static const uint s_default_palette[20];  // 预定义默认调色板（包含20种高辨识度颜色，以十六进制RGB值存储，如 0x3366CC 对应 #3366CC 蓝色）

public:
   /**
    * @brief 构造函数：创建颜色生成器实例并初始化状态
    * @note 初始化逻辑：
    *       1. 将生成索引 m_index 重置为 0（从第一个预定义颜色开始分配）；
    *       2. 关闭动态生成开关 m_generate（初始使用预定义调色板）；
    *       3. 复制预定义调色板 s_default_palette 到当前调色板 m_current_palette；
    */
                     CColorGenerator(void);

   /**
    * @brief 析构函数：清理颜色生成器资源
    * @note 无动态内存分配（调色板为固定大小数组），仅重置内部状态
    */
                    ~CColorGenerator(void);

   /**
    * @brief 获取下一个颜色（核心生成方法）
    * @return uint - 生成的颜色值（以十六进制 RGB 格式存储，如 0xDC3912 对应 #DC3912 红色，可直接用于 MQL5 图形接口）
    * @note 生成逻辑（按顺序执行）：
    *       1. 索引检查：若 m_index 达到 20（预定义颜色用尽），重置索引为 0 并开启动态生成开关 m_generate；
    *       2. 颜色获取：
    *          - 若 m_generate = false（预定义阶段）：直接返回当前调色板 m_current_palette[m_index]；
    *          - 若 m_generate = true（动态生成阶段）：通过“异或运算”更新当前调色板元素（当前元素与下一个元素异或，最后一个元素与第一个元素异或），再返回更新后的值；
    *       3. 索引递增：m_index 自增 1，为下一次调用做准备；
    */
   uint              Next(void);

   /**
    * @brief 重置颜色生成器状态（恢复初始配置）
    * @note 重置逻辑：
    *       1. 将生成索引 m_index 重置为 0；
    *       2. 关闭动态生成开关 m_generate；
    *       3. 重新复制预定义调色板 s_default_palette 到当前调色板 m_current_palette，覆盖动态生成的颜色；
    *       适用场景：需要重新开始分配颜色的场景（如重置图表、切换数据序列集）；
    */
   void              Reset(void);
  };

// 预定义默认调色板初始化（包含 20 种高辨识度颜色，覆盖主流色系，避免视觉混淆，适用于大多数可视化场景）
const uint CColorGenerator::s_default_palette[20] =
  {
   0x3366CC,  // 蓝色 (#3366CC)
   0xDC3912,  // 红色 (#DC3912)
   0xFF9900,  // 橙色 (#FF9900)
   0x109618,  // 绿色 (#109618)
   0x990099,  // 紫色 (#990099)
   0x3B3EAC,  // 深蓝色 (#3B3EAC)
   0x0099C6,  // 青蓝色 (#0099C6)
   0xDD4477,  // 粉紫色 (#DD4477)
   0x66AA00,  // 黄绿色 (#66AA00)
   0xB82E2E,  // 深红色 (#B82E2E)
   0x316395,  // 靛蓝色 (#316395)
   0x994499,  // 暗紫色 (#994499)
   0x22AA99,  // 青绿色 (#22AA99)
   0xAAAA11,  // 明黄色 (#AAAA11)
   0x6633CC,  // 蓝紫色 (#6633CC)
   0xE67300,  // 深橙色 (#E67300)
   0x8B0707,  // 暗红色 (#8B0707)
   0x329262,  // 深绿色 (#329262)
   0x5574A6,  // 灰蓝色 (#5574A6)
   0x3B3EAC   // 深蓝色（与第6个颜色相同，作为调色板收尾，动态生成时用于异或运算）
  };
//+------------------------------------------------------------------+